<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<style type="text/css">
body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,textarea,p,blockquote,th,td{margin:0;padding:0;}
/* YAHOO FONTS =========================================== */

body{font:13px/18px arial,helvetica,clean,sans-serif;background:url('/images/f/backgrounds/18px_grid.gif') repeat;}

p { margin-top:18px; margin-bottom:18px;}

table {border-collapse:collapse;}
code { font: normal 100% Monospace; }

td {line-height:18px;}
/*	pre, code, kbd, samp, tt { font-family:monospace;*font-size:100%;}*/
</style>
  <!--[if IE]>
    <style type="text/css">
    	code { font: normal 100%/18px monospace;}
	</style>
    <![endif]-->
</head>

<body>

<h1>ActionMailer Cheatsheet</h1>

<h2>ActionMailer is the Rails framework which handles email delivery. This comprehensive cheatsheet will help your email on its way.</h2>


<div id="article"><h1 id='table_of_contents'>Table of Contents</h1>
<div class='maruku_toc'><ul style='list-style: none;'><li><span class='maruku_section_number'>1. </span><a href='#mailer_model'>Mailer Model</a><ul style='list-style: none;'><li><span class='maruku_section_number'>1.1. </span><a href='#mailer_model_generator'>Mailer model generator</a></li><li><span class='maruku_section_number'>1.2. </span><a href='#example_mailer_model'>Example mailer model</a></li></ul></li><li><span class='maruku_section_number'>2. </span><a href='#delivering_mail'>Delivering mail</a><ul style='list-style: none;'><li><span class='maruku_section_number'>2.1. </span><a href='#send_mail'>Send mail</a></li><li><span class='maruku_section_number'>2.2. </span><a href='#create_mail'>Create mail</a></li></ul></li><li><span class='maruku_section_number'>3. </span><a href='#multipart_messages'>Multipart messages</a><ul style='list-style: none;'><li><span class='maruku_section_number'>3.1. </span><a href='#explicitly'>Explicitly</a></li><li><span class='maruku_section_number'>3.2. </span><a href='#implicitly'>Implicitly</a></li></ul></li><li><span class='maruku_section_number'>4. </span><a href='#views__templates'>Views &amp; Templates</a><ul style='list-style: none;'><li><span class='maruku_section_number'>4.1. </span><a href='#making_variables_available_to_the_view'>Making variables available to the view</a><ul style='list-style: none;'><li><span class='maruku_section_number'>4.1.1. </span><a href='#model'>Model</a></li><li><span class='maruku_section_number'>4.1.2. </span><a href='#view'>View</a></li></ul></li></ul></li><li><span class='maruku_section_number'>5. </span><a href='#mailer_configuration_methods'>Mailer Configuration Methods</a></li><li><span class='maruku_section_number'>6. </span><a href='#urls'>URLs</a></li><li><span class='maruku_section_number'>7. </span><a href='#actionmailerbase_configuration_methods'>ActionMailer::Base Configuration Methods</a></li><li><span class='maruku_section_number'>8. </span><a href='#setting_attachments'>Setting attachments</a></li><li><span class='maruku_section_number'>9. </span><a href='#smtp_settings'>smtp_settings</a></li></ul></div>
<h2 id='mailer_model'><span class='maruku_section_number'>1. </span>Mailer Model</h2>

<p>To use ActionMailer, you need to create a mailer model. Emails are defined by creating methods within the mailer model which are then used to set variables to be used in the mail template, to change options on the mail, or to add attachments.</p>

<h3 id='mailer_model_generator'><span class='maruku_section_number'>1.1. </span>Mailer model generator</h3>

<pre>ruby script/generate mailer NameOfMailer method1 method2 method3</pre>

<h3 id='example_mailer_model'><span class='maruku_section_number'>1.2. </span>Example mailer model</h3>

<pre class="ruby"><span class='r'>class</span> <span class='cl'>OrderMailer</span> &lt; <span class='co'>ActionMailer</span>::<span class='co'>Base</span>

    <span class='r'>def</span> <span class='fu'>confirm</span>(order,sent_at = <span class='co'>Time</span>.now)
        subject    <span class='s'><span class='dl'>&quot;</span><span class='k'>Subject line goes here</span><span class='dl'>&quot;</span></span>
        body       <span class='sy'>:order</span> =&gt; order
        recipients [<span class='s'><span class='dl'>&quot;</span><span class='k'>bill@microsoft.com</span><span class='dl'>&quot;</span></span>, <span class='s'><span class='dl'>&quot;</span><span class='k'>steve@apple.com</span><span class='dl'>&quot;</span></span>]
        from       <span class='s'><span class='dl'>&quot;</span><span class='k'>david@dizzy.co.uk</span><span class='dl'>&quot;</span></span>
        sent_on    sent_at
    <span class='r'>end</span>    
<span class='r'>end</span></pre>

<h2 id='delivering_mail'><span class='maruku_section_number'>2. </span>Delivering mail</h2>

<p>Once a mailer action and template are defined, you can deliver your message or create and save it for delivery later by calling the mailer class and prefixing your chosen class method with <code>deliver_</code> or <code>create_</code></p>

<h3 id='send_mail'><span class='maruku_section_number'>2.1. </span>Send mail</h3>

<pre class="ruby"><span class='co'>Notifier</span>.deliver_signup_notification(customer)</pre>

<h3 id='create_mail'><span class='maruku_section_number'>2.2. </span>Create mail</h3>

<pre class="ruby">mail = <span class='co'>Notifier</span>.create_signup_notification(customer)
<span class='co'>Notifier</span>.deliver(mail)</pre>

<p>You can pass the mailer model any variables you need to use in the generation of the email. In the example above we have passed it a variable named <code>customer</code> which could be an instance of an ActiveRecord <code>Customer</code> model. We can then access our customer&#8217;s details in the mailer model.</p>

<h2 id='multipart_messages'><span class='maruku_section_number'>3. </span>Multipart messages</h2>

<p>There are two ways to send multipart email messages, explicity by manually defining each part, and implicitly by letting ActionMailer do the donkey work.</p>

<h3 id='explicitly'><span class='maruku_section_number'>3.1. </span>Explicitly</h3>

<p>You can explicitly define multipart messages using the part method&#8230;</p>

<pre class="ruby">part <span class='s'><span class='dl'>&quot;</span><span class='k'>text/plain</span><span class='dl'>&quot;</span></span> <span class='r'>do</span> |p|
    p.body = render_message(<span class='s'><span class='dl'>&quot;</span><span class='k'>signup-as-plain</span><span class='dl'>&quot;</span></span>, <span class='sy'>:account</span> =&gt; recipient)
    p.transfer_encoding = <span class='s'><span class='dl'>&quot;</span><span class='k'>base64</span><span class='dl'>&quot;</span></span>
<span class='r'>end</span>

part <span class='sy'>:content_type</span> =&gt; <span class='s'><span class='dl'>&quot;</span><span class='k'>text/html</span><span class='dl'>&quot;</span></span>, <span class='sy'>:body</span> =&gt; render_message(<span class='s'><span class='dl'>&quot;</span><span class='k'>signup-as-html</span><span class='dl'>&quot;</span></span>, <span class='sy'>:account</span> =&gt; recipient)</pre>

<h3 id='implicitly'><span class='maruku_section_number'>3.2. </span>Implicitly</h3>

<p>ActionMailer will automatically detect and use multipart templates, where each template is named after the name of the method, followed by the content type. Each such detected template will be added as a separate part to the message. For example:</p>

<pre>signup_notification.text.plain.erb
signup_notification.text.html.erb
signup_notification.text.xml.builder</pre>

<p>Each would be rendered and added as a separate part to the message with the corresponding content type. The same body hash is passed to each template.</p>

<h2 id='views__templates'><span class='maruku_section_number'>4. </span>Views &amp; Templates</h2>

<p>Like ActionController, each mailer class has a corresponding view directory in which each method of the class looks for a template with its own name. For example&#8230;</p>
<table><thead><tr><th>Mailer model</th><th>Class method</th><th>Corresponding template</th></tr></thead><tbody><tr><td style='text-align: left;'><code>Notifier</code></td><td style='text-align: left;'><code>signup_notification</code></td><td style='text-align: left;'><code>app/views/notifier/signup_notification.erb</code></td>
</tr><tr><td style='text-align: left;'><code>Notifier</code></td><td style='text-align: left;'><code>despatch_alert</code></td><td style='text-align: left;'><code>app/views/notifier/despatch_alert.erb</code></td>
</tr><tr><td style='text-align: left;'><code>MailingList</code></td><td style='text-align: left;'><code>welcome_message</code></td><td style='text-align: left;'><code>app/views/mailing_list/welcome_message.erb</code></td>
</tr></tbody></table>
<h3 id='making_variables_available_to_the_view'><span class='maruku_section_number'>4.1. </span>Making variables available to the view</h3>

<p>The <code>body</code> method is used to pass variables to the view. Each variable passed will be accessible as an <code>@instance_variable</code> with the name referenced by <code>:symbol</code>.</p>

<h4 id='model'><span class='maruku_section_number'>4.1.1. </span>Model</h4>

<pre class="ruby">body <span class='sy'>:order</span> =&gt; order, <span class='sy'>:name</span> =&gt; name</pre>

<h4 id='view'><span class='maruku_section_number'>4.1.2. </span>View</h4>

<pre><span class='il'><span class='idl'>&lt;%=</span> <span class='iv'>@order</span> <span class='idl'>%&gt;</span></span>
<span class='il'><span class='idl'>&lt;%=</span> <span class='iv'>@name</span> <span class='idl'>%&gt;</span></span></pre>

<h2 id='mailer_configuration_methods'><span class='maruku_section_number'>5. </span>Mailer Configuration Methods</h2>
<table><thead><tr><th>Method</th><th>Value</th><th>Purpose</th></tr></thead><tbody><tr><td style='text-align: left;'><code>recipients</code></td><td style='text-align: left;'><code>[array]</code> <em>or</em> <code>&quot;string&quot;</code></td><td style='text-align: left;'>A <code>&quot;string&quot;</code> containing the email of address of the recipient, or an <code>[array]</code> of <code>&quot;strings&quot;</code> &#8220;containing email addresses of multiple recipients. Will use the email&#8217;s <code>To:</code> header.</td>
</tr><tr><td style='text-align: left;'><code>sent_on</code></td><td style='text-align: left;'><code>Time</code> <em>object</em></td><td style='text-align: left;'>A <code>Time</code> object which will be used to set the <code>Date:</code> header of the email. If not specified, then the current time and date will be used.</td>
</tr><tr><td style='text-align: left;'><code>subject</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>The subject line to be used to set the email&#8217;s <code>Subject:</code> header.</td>
</tr><tr><td style='text-align: left;'><code>from</code></td><td style='text-align: left;'><code>[array]</code> <em>or</em> <code>&quot;string&quot;</code></td><td style='text-align: left;'>A <code>&quot;string&quot;</code> containing the email address to appear on the <code>From:</code> line of the email being created, or an <code>[array]</code> of <code>&quot;strings&quot;</code> containing multiple email addresses in the same format as recipients.</td>
</tr><tr><td style='text-align: left;'><code>body</code></td><td style='text-align: left;'><code>{hash}</code></td><td style='text-align: left;'>The <code>body</code> method sets instance variables to be available in the view template</td>
</tr><tr><td style='text-align: left;'><code>attachment</code></td><td style='text-align: left;'><code>{hash}</code> <em>or</em> <code>block</code></td><td style='text-align: left;'>Enables you to add attachments to your email message.</td>
</tr><tr><td style='text-align: left;'><code>bcc</code></td><td style='text-align: left;'><code>[array]</code> <em>or</em> <code>&quot;string&quot;</code></td><td style='text-align: left;'>Blind carbon copy recipients in the same format as <code>recipients</code>.</td>
</tr><tr><td style='text-align: left;'><code>cc</code></td><td style='text-align: left;'><code>[array]</code> <em>or</em> <code>&quot;string&quot;</code></td><td style='text-align: left;'>Carbon copy recipients in the same format as <code>recipients</code></td>
</tr><tr><td style='text-align: left;'><code>content_type</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>Set the <code>content_type</code> of the message. Defaults to <code>text/plain</code></td>
</tr><tr><td style='text-align: left;'><code>headers</code></td><td style='text-align: left;'><code>{hash}</code></td><td style='text-align: left;'>A <code>{hash}</code> containing name/value pairs <sup id='fnref:1'><a href='#fn:1' rel='footnote'>1</a></sup> to be converted into abitrary header lines.</td>
</tr><tr><td style='text-align: left;'><code>mime_version</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>The mime version for the message. Defaults to <code>1.0</code></td>
</tr><tr><td style='text-align: left;'><code>charset</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>The <code>charset</code> for the body and to encode the subject. Defaults to <code>UTF-8</code></td>
</tr><tr><td style='text-align: left;'><code>implicit_parts_order</code></td><td style='text-align: left;'><code>[array]</code></td><td style='text-align: left;'>When an email is built implicitly, this variable controls how the parts are ordered. Defaults to <code>[&quot;text/html&quot;, &quot;text/enriched&quot;, &quot;text/plain&quot;]</code>. Items that appear first in the <code>[array]</code> have higher priority in the receiving mail client and appear last in the mime encoded message.</td>
</tr></tbody></table>
<h2 id='urls'><span class='maruku_section_number'>6. </span>URLs</h2>

<p>If your view includes URLs from the application, you need to use <code>url_for</code> in the mailer class method instead of in the view template. You can pass the result to the view via the <code>body</code> method. Unlike controllers from ActionPack, the mailer instance doesn&#8217;t have any context about the incoming request, therefore you need to define the host, using <code>:host</code>.</p>

<pre class="ruby">body <span class='sy'>:home_page</span> =&gt; url_for(<span class='sy'>:host</span> =&gt; <span class='s'><span class='dl'>&quot;</span><span class='k'>dizzy.co.uk</span><span class='dl'>&quot;</span></span>, <span class='sy'>:controller</span> =&gt; <span class='s'><span class='dl'>&quot;</span><span class='k'>welcome</span><span class='dl'>&quot;</span></span>, <span class='sy'>:action</span> =&gt; <span class='s'><span class='dl'>&quot;</span><span class='k'>index</span><span class='dl'>&quot;</span></span>)</pre>

<h2 id='actionmailerbase_configuration_methods'><span class='maruku_section_number'>7. </span>ActionMailer::Base Configuration Methods</h2>

<p>ActionMailer is configured by accessing configuration methods at the class level. For example:</p>

<pre class="ruby"><span class='co'>ActionMailer</span>::<span class='co'>Base</span>.template_root = <span class='s'><span class='dl'>&quot;</span><span class='k'>/my/templates</span><span class='dl'>&quot;</span></span></pre>

<p>These methods allow you to define the overall settings to be used by your application whenever it invokes ActionMailer. Define these settings in your <code>config/environment.rb</code> file using <code>config.action_mailer.method_name_here</code>. If you require different settings for each of your Rails&#8217; environments, define settings separately via <code>config/environments</code>.</p>
<table><thead><tr><th>Method</th><th>Value</th><th>Purpose</th></tr></thead><tbody><tr><td style='text-align: left;'><code>smtp_settings</code></td><td style='text-align: left;'><code>{hash}</code></td><td style='text-align: left;'>A <code>{hash}</code> of settings  for the SMTP mail server</td>
</tr><tr><td style='text-align: left;'><code>raise_delivery_errors</code></td><td style='text-align: left;'><code>true</code> <em>or</em> <code>false</code></td><td style='text-align: left;'>Whether or not errors should be raised if the email fails to be delivered.</td>
</tr><tr><td style='text-align: left;'><code>delivery_method</code></td><td style='text-align: left;'><code>:smtp</code>, <code>:sendmail</code> <em>or</em> <code>:test</code></td><td style='text-align: left;'>Defines a delivery method, defaults to <code>:smtp</code></td>
</tr><tr><td style='text-align: left;'><code>perform_deliveries</code></td><td style='text-align: left;'><code>true</code> <em>or</em> <code>false</code></td><td style='text-align: left;'>Determines whether <code>deliver_*</code> methods are actually carried out. By default they are, but this can be turned off to help functional testing.</td>
</tr><tr><td style='text-align: left;'><code>template_root</code></td><td style='text-align: left;'><code>&quot;/path&quot;</code></td><td style='text-align: left;'>The root from which template references will be made</td>
</tr><tr><td style='text-align: left;'><code>logger</code></td><td style='text-align: left;'><em>Object</em></td><td style='text-align: left;'>Used for generation information on the mailing run if available. Can be set to <code>nil</code> for no logging. Compatible with Ruby&#8217;s own <code>Logger</code> and <code>Log4r</code> loggers.</td>
</tr><tr><td style='text-align: left;'><code>default_charset</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>the default <code>charset</code> used for the body and to encode the subject. Defaults to <code>UTF-8</code>. You can also pick a different <code>charset</code> from inside a mailer method by setting charset</td>
</tr><tr><td style='text-align: left;'><code>default_mime_version</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>The default mime version used for the message. Defaults to <code>1.0</code>. You can also pick a different value from inside a mailer method by setting <code>mime_version</code></td>
</tr><tr><td style='text-align: left;'><code>default_implicit_parts_order</code></td><td style='text-align: left;'><code>[array]</code></td><td style='text-align: left;'>When an email is built implicitly, this variable controls how the parts are ordered. Defaults to <code>[&quot;text/html&quot;, &quot;text/enriched&quot;, &quot;text/plain&quot;]</code>. Items that appear first in the <code>[array]</code> have higher priority in the receiving mail client and appear last in the mime encoded message. You can also pick a different value from inside a mailer method by setting <code>implicit_parts_order</code></td>
</tr><tr><td style='text-align: left;'><code>default_content_type</code></td><td style='text-align: left;'><code>&quot;string&quot;</code></td><td style='text-align: left;'>The default <code>content_type</code> used for the main part of the message. Defaults to <code>text/plain</code>. You can also pick a different value from inside a mailer method by setting <code>content_type</code></td>
</tr></tbody></table>
<h2 id='setting_attachments'><span class='maruku_section_number'>8. </span>Setting attachments</h2>

<pre class="ruby">attachment <span class='sy'>:content_type</span> =&gt; <span class='s'><span class='dl'>&quot;</span><span class='k'>image/jpeg</span><span class='dl'>&quot;</span></span>, <span class='sy'>:body</span> =&gt; <span class='co'>File</span>.read(<span class='s'><span class='dl'>&quot;</span><span class='k'>an-image.jpg</span><span class='dl'>&quot;</span></span>)
attachment <span class='s'><span class='dl'>&quot;</span><span class='k'>application/pdf</span><span class='dl'>&quot;</span></span> <span class='r'>do</span> |a| 
  a.body = generate_your_pdf_here()
<span class='r'>end</span></pre>

<h2 id='smtp_settings'><span class='maruku_section_number'>9. </span>smtp_settings</h2>
<table><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td style='text-align: left;'><code>:address</code></td><td style='text-align: left;'>the address of the SMTP server you will be using to send email. Defaults to <code>localhost</code></td>
</tr><tr><td style='text-align: left;'><code>:port</code></td><td style='text-align: left;'>the port number of the SMTP server you will be using. Defaults to <code>25</code></td>
</tr><tr><td style='text-align: left;'><code>:domain</code></td><td style='text-align: left;'>if you need to specify a <code>HELO</code> domain, you can do it here</td>
</tr><tr><td style='text-align: left;'><code>:user_name</code></td><td style='text-align: left;'>if your mail server requires authentication, set the username in this variable</td>
</tr><tr><td style='text-align: left;'><code>:password</code></td><td style='text-align: left;'>if your mail server requires authentication, set the password in this variable</td>
</tr><tr><td style='text-align: left;'><code>:authentication</code></td><td style='text-align: left;'>if your mail server requires authentication, you need to specify the authentication type here. This is a symbol, and one of <code>:plain</code>, <code>:login</code>, or <code>:cram_md5</code></td>
</tr></tbody></table><div class='footnotes'><hr /><ol><li id='fn:1'>
<p>Name value pairs for setting headers</p>

<pre class="ruby">headers <span class='s'><span class='dl'>&quot;</span><span class='k'>X-Mail-Count</span><span class='dl'>&quot;</span></span> =&gt; <span class='i'>107370</span></pre>
<a href='#fnref:1' rev='footnote'>&#8617;</a></li></ol></div></div>
</body>
</html>